IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/Vk/VkNameList.z/VkNameList

Text File | 2002-10-03 | 17.6 KB | 529 lines

VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))                                                  VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))



NNNNAAAAMMMMEEEE
     VkNameList - A class that supports and manipulates lists of strings

HHHHEEEEAAAADDDDEEEERRRR FFFFIIIILLLLEEEE
     #include <Vk/VkNameList.h>

PPPPUUUUBBBBLLLLIIIICCCC PPPPRRRROOOOTTTTOOOOCCCCOOOOLLLL SSSSUUUUMMMMMMMMAAAARRRRYYYY
   CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr////DDDDeeeessssttttrrrruuuuccccttttoooorrrr
           VkNameList(void);

           VkNameList(const VkNameList& givenList);

           VkNameList(char* name);

           void ~VkNameList(void);



   AAAAddddddddiiiinnnngggg aaaannnndddd RRRReeeemmmmoooovvvviiiinnnngggg IIIItttteeeemmmmssss
           void add(char* name);

           void add(const VkNameList& givenList);

           void getIndex(const char* name);

           void remove(char* name);

           void remove(int index, int count=1);

           VkNameList& operator=(const VkNameList& givenList);



   MMMMaaaannnniiiippppuuuullllaaaattttiiiinnnngggg TTTThhhheeee LLLLiiiisssstttt
           void sort(void);

           void reverse(void);

           void removeDuplicates(void);



   AAAAcccccccceeeessssssss FFFFuuuunnnnccccttttiiiioooonnnnssss
           int size(void);

           int exists(char* name);

           char* operator[](int index);

           VkNameList operator[](char* subString);

           int operator==(const VkNameList& givenList);



                                                                        PPPPaaaaggggeeee 1111






VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))                                                  VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))



           char* mostCommonString(void);

           VkNameList* completeName(char* name,
                                    char&* completedName,
                                    int& nMatching);

           char** operator char **(void);

           XmStringTable operator unsigned char **(void);

           char*  getString(int index);

           char*  getSubStrings(char *subString);

           char** getStringTable();

           XmStringTable getXmStringTable();

           static void freeXmStringTable (XmStringTable);



CCCCLLLLAAAASSSSSSSS DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
          VkNameList provides a convenient way to maintain a list of character
          strings. Strings can be added or removed individually, the list can
          be sorted or reversed, duplications can be removed, the best
          completion of a substring can be found, the most common occurrence
          can be computed, and so on. The list can also be automatically
          converted to a XmStringTable, making this a useful class for use
          with Motif widgets that require a list of compound strings.

          Some of the VkNameList operators allocate memory that must later be
          freed by the caller. This can be counter-intuitive, and a source of
          memory leaks.  To avoid that, alternate conventional functions are
          also provided.  The conventional functions make it more clear that
          there is something to be freed.  In one case (_g_e_t_S_u_b_S_t_r_i_n_g_s()), the
          conventional function is also considerably more efficient.

          The operators to be careful of are:  _o_p_e_r_a_t_o_r[](_i_n_t) (prefer
          getString(int)); _o_p_e_r_a_t_o_r[](_c_h_a_r*) (prefer getSubStrings(char*));
          _o_p_e_r_a_t_o_r _c_h_a_r**() (prefer getStringTable()); _o_p_e_r_a_t_o_r
          _X_m_S_t_r_i_n_g_T_a_b_l_e() (prefer getXmStringTable());


FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNN DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNNSSSS
   VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt(((())))
           VkNameList(void);

           VkNameList(char* name);

           VkNameList(const VkNameList& givenList);




                                                                        PPPPaaaaggggeeee 2222






VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))                                                  VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))



          Initialize a VkNameList object. The first form initializes an empty
          list, while the second allows allows an initial member of the list
          to be specified. The copy constructor produces a clone of an
          existing VkNameList object.


   ~~~~VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt(((())))
           void ~VkNameList(void);


          Free all memory allocated by a VkNameList object.


   aaaadddddddd(((())))
           void add(char *item);

           void add(const VkNameList& list);


          Add an item or a VkNameList to the list.


   ggggeeeettttIIIInnnnddddeeeexxxx(((())))
           int getIndex(const char *item) const;


          Gets the index of the first occurrence of the given item from the
          list.  If the item does not exist, the index returned is -1.


   rrrreeeemmmmoooovvvveeee(((())))
           void remove(char *item);


          Remove the first occurrence, if any, of the given item from the
          list.


   rrrreeeemmmmoooovvvveeee(((())))
           void remove(int index, count=1);


          Remove the items _i_n_d_e_x through _i_n_d_e_x+_c_o_u_n_t-_1 from the list.  _C_o_u_n_t
          items, beginning with a named item, can be removed with the idiom
          _r_e_m_o_v_e(_g_e_t_I_n_d_e_x(_i_t_e_m),_c_o_u_n_t);


   ssssoooorrrrtttt(((())))
           void sort(void);






                                                                        PPPPaaaaggggeeee 3333






VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))                                                  VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))



          Sort the items on the list alphanumerically.


   rrrreeeevvvveeeerrrrsssseeee(((())))
           void reverse(void);


          Reverse the order of the items on the list.


   rrrreeeemmmmoooovvvveeeeDDDDuuuupppplllliiiiccccaaaatttteeeessss(((())))
           void removeDuplicates(void);


          Remove all exact duplicates from the list.


   ssssiiiizzzzeeee(((())))
           int size(void);


          Returns the number of elements in the list.


   eeeexxxxiiiissssttttssss(((())))
           int exists(char *item);


          Returns non-zero if the specified string is a member of the list.



   ooooppppeeeerrrraaaattttoooorrrr====(((())))
           VkNameList& operator=(const VkNameList&);


          Assign the members of one list to another.  Note that this frees any
          strings that were in the old object.  Any references to them, such
          as those returned by a previous call to _o_p_e_r_a_t_o_r _c_h_a_r **(), now
          point to free'd memory.


   ooooppppeeeerrrraaaattttoooorrrr[[[[]]]](((())))
           char* operator[](int index);


          Retrieve a copy of an item from the list by index.  The returned
          string must be freed by the caller.

          For clarity in the application code, _g_e_t_S_t_r_i_n_g(_i_n_t _i_n_d_e_x) is
          preferred.




                                                                        PPPPaaaaggggeeee 4444






VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))                                                  VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))



   ggggeeeettttSSSSttttrrrriiiinnnngggg(((())))
           char* getString(int index);

               Retrieve a copy of an item from the list by index.
               The returned string must be freed by the caller.



   ooooppppeeeerrrraaaattttoooorrrr[[[[]]]](((())))
           VkNameList operator[](char* substring);


          Return a list of items that match the given substring.  The returned
          object must be delete'd by the caller.

          Both for clarity in the application code, and for efficiency,
          _g_e_t_S_u_b_S_t_r_i_n_g_s(_c_h_a_r *) is preferred.


   ggggeeeettttSSSSuuuubbbbSSSSttttrrrriiiinnnnggggssss(((())))
           VkNameList* getSubStrings(char* substring);


          Return a pointer to a list of items that match the given substring.
          The returned _V_k_N_a_m_e_L_i_s_t must be delete'd by the caller.


   ooooppppeeeerrrraaaattttoooorrrr========(((())))
           int operator==(const VkNameList&);


          Text for equivalence of two VkNameList objects. The lists must have
          identical contents in the same order for the test to return success.


   mmmmoooossssttttCCCCoooommmmmmmmoooonnnnSSSSttttrrrriiiinnnngggg(((())))
           char* mostCommonString(void);


          Return a copy of the most common string in a list.  The returned
          string must be freed by the caller.


   ccccoooommmmpppplllleeeetttteeeeNNNNaaaammmmeeee(((())))
           VkNameList* completeName(char  *name,
                                    char &*completed name,
                                    int&   numMatching);


          Given a string, this function returns a VkNameList object containing
          all strings in the original list that could be completions of the
          given string. Upon returning, the _c_o_m_p_l_e_t_e_d_N_a_m_e argument contains



                                                                        PPPPaaaaggggeeee 5555






VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))                                                  VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))



          the matched substring common to all members of the returned list.
          Finally, the _n_u_m_M_a_t_c_h_i_n_g reports the number of matched elements.


   ooooppppeeeerrrraaaattttoooorrrr(((())))
           char** operator char **(void);


          This operator returns a pointer to the members of a _V_k_N_a_m_e_L_i_s_t
          object as as an array of strings.  The strings in the returned array
          _M_U_S_T _N_O_T be freed by the caller.  The array itself must be freed by
          the caller.

          For clarity in the application code, _g_e_t_S_t_r_i_n_g_T_a_b_l_e() is preferred.


   ggggeeeettttSSSSttttrrrriiiinnnnggggTTTTaaaabbbblllleeee(((())))
           char** getStringTable(void);


          This operator returns a pointer to the members of a _V_k_N_a_m_e_L_i_s_t
          object as as an array of strings.  The strings in the returned array
          _M_U_S_T _N_O_T be freed by the caller.  The array itself must be freed by
          the caller.


   ooooppppeeeerrrraaaattttoooorrrr(((())))
           XmStringTable operator unsigned char **(void);


          This operator provides access to the members of a _V_k_N_a_m_e_L_i_s_t object
          as as an array of compound strings.  The returned XmStringTable must
          be freed by the caller.  (See _f_r_e_e_X_m_S_t_r_i_n_g_T_a_b_l_e).

          For clarity in the application code, _g_e_t_X_m_S_t_r_i_n_g_T_a_b_l_e() is
          preferred.


   ggggeeeettttXXXXmmmmSSSSttttrrrriiiinnnnggggTTTTaaaabbbblllleeee(((())))
           XmStringTable getXmStringTable(void);


          This operator provides access to the members of a _V_k_N_a_m_e_L_i_s_t object
          as as an array of compound strings.  The returned XmStringTable must
          be freed by the caller.  (See _f_r_e_e_X_m_S_t_r_i_n_g_T_a_b_l_e).


   ffffrrrreeeeeeeeXXXXmmmmSSSSttttrrrriiiinnnnggggTTTTaaaabbbblllleeee
           static void freeXmStringTable (XmStringTable)






                                                                        PPPPaaaaggggeeee 6666






VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))                                                  VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))



          This function frees the memory returned by _X_m_S_t_r_i_n_g_T_a_b_l_e _o_p_e_r_a_t_o_r
          (), or by _g_e_t_X_m_S_t_r_i_n_g_T_a_b_l_e().

EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
     The following example uses a VkNameList to construct a list
     incrementally, and display the resulting list in reverse sorted order in
     a Motif XmList widget.


           #include <Vk/VkApp.h>
           #include <Vk/VkSimpleWindow.h>
           #include <Xm/List.h>
           #include <Vk/VkNameList.h>

           // Define a top-level window class

           class MyWindow: public VkSimpleWindow {

            protected:

              Widget _list;    // Hang on to widget as a data member

            public:

              MyWindow ( const char *name );
              ~MyWindow();
              virtual const char* className();  // Identify this class
           };

           // The MyWindow constructor provides a place in which
           // to create a widget tree to be installed as a
           // "view" in the window.

           MyWindow::MyWindow ( const char *name ) :
                            VkSimpleWindow ( name )
           {
              _list =  XmCreateList ( mainWindowWidget(),
                                      "list", NULL, 0 );

              // Create a name list object

              VkNameList *items = new VkNameList();

              // Add some items

              items->add("One");
              items->add("Two");
              items->add("Three");
              items->add("Four");
              items->add("One");

              items->removeDuplicates();  // Get rid of duplications



                                                                        PPPPaaaaggggeeee 7777






VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))                                                  VVVVkkkkNNNNaaaammmmeeeeLLLLiiiisssstttt((((3333xxxx))))



              items->sort();              // sort the list
              items->reverse();           // Now reverse it

              // Display the items in the list widget

              XtVaSetValues(_list,
                            XmNitems, (XmStringTable) (*items),
                            XmNitemCount, items->size(),
                            NULL);

              addView(_list);
           }

           const char * MyWindow::className()
           {
              return "MyWindow";
           }

           MyWindow::~MyWindow()
           {
              // Empty
           }

           // Main driver. Just instantiate a VkApp and a
           // top-level window, "show" the window and then
           // "run" the application.

           void main ( int argc, char **argv )
           {
              VkApp     *app = new VkApp("Hello", &argc, argv);
              MyWindow  *win = new MyWindow("hello");

              win->show();
              app->run();
           }



KKKKNNNNOOOOWWWWNNNN CCCCLLLLAAAASSSSSSSSEEEESSSS TTTTHHHHAAAATTTT UUUUSSSSEEEE TTTTHHHHIIIISSSS CCCCLLLLAAAASSSSSSSS
     VkCompletionField

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     VkCompletionField
     _V_i_e_w_K_i_t _P_r_o_g_r_a_m_m_e_r'_s _G_u_i_d_e
     _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m, DEC Press, Bob Sheifler and Jim Gettys
     _T_h_e _X _W_i_n_d_o_w _S_y_s_t_e_m _T_o_o_l_k_i_t, DEC Press, Paul Asente and Ralph Swick
     _T_h_e _O_S_F/_M_o_t_i_f _P_r_o_g_r_a_m_m_e_r_s _R_e_f_e_r_e_n_c_e, Prentice Hall, OSF








                                                                        PPPPaaaaggggeeee 8888